/*
 * To change this template, choose Tools | Templates
 * and open the template in the editor.
 */

package eu.livotov.tdv.api;

import java.io.InputStream;

/**
 * Interface to provide support for any kind of file formats in order to let TDV to undrestand and display it.
 * This is the main interface you must implement in order to add support for a new file format.
 * @author dlivotov
 */
public interface DocumentRasterProvider
{
    /**
     * Provides an unique string to identify your document. This string must be unique on the server where webapp is
     * used. TDV will use the identifier given when creating temporary cache folders.
     * @return unique (server-wide) identifier for the document being serviced
     */
    String getDocumentId();

    /**
     * Provides actual number of pages in the document
     * @return number of pages in the document
     */
    int getPagesCount();

    /**
     * Provides specified page raster as an input stream. The ratser must be provided as a PNG image data. TDV will be actively
     * caching page raster fragments, so please do not implement any caching mechanisms here to avoid mixups.
     * @param pageNumber page number to get raster of. Page numbers are set from 1 to max number.
     * @param zoomLevel zoom level in percent from 0.1 to x.y, where 0.5 is 50%, 1.0 is 100%, etc...
     * @param rotationLevel rotation level of the page in degrees.
     * @return PNG stream of rasterized page.
     */
    InputStream getPageData( int pageNumber, float zoomLevel, int rotationLevel );

    /**
     * Provides thumbnail of a specified page. Implementor must fit the page picture into the bounding box, specified
     * by the thumbnail width and height, leaving transparent margins if necessary.
     * @param pageNumber page number to provide thumbnail for. Page numbers are set from 1 to max.
     * @param thWidth width of the thumbnail image
     * @param thHeight height of the thumbnail image
     * @return page thumbnail as PNG picture, fit into the width/height specified bounding box with the transparent margins where necessary.
     */
    InputStream getPageThumbnail ( int pageNumber, int thWidth, int thHeight );

    /**
     * Provides properties of the ratserized page, that is generated by the getPageData method.
     * @param pageNumber page number from 1 to N
     * @param zoomLevel zoom level
     * @param rotationLevel rotation level
     * @return raster properties.
     */
    RasterizedPageProperties getPageProperties ( int pageNumber, float zoomLevel, int rotationLevel );

    /**
     * Provides properties of the ratserized page thumbnail, that is generated by the getPageThumbnail method.
     * @param pageNumber page number from 1 to N
     * @param thumbnailPanelWidth width of thumbnail panel
     * @return raster properties.
     */
    RasterizedPageProperties getPageThumbnailProperties ( int pageNumber, int thumbnailPanelWidth);

    /**
     * Should close the page document and release any files open or locked. After this method is invoked, no other methods of the same
     * instance will be ever called by TDV.
     */
    void closeDocument();
}
